REST API設計
学習リソース
このガイドは、gRPC API を中心に、REST API と RPC API の両方に適用
RPC API は、多くの場合、インターフェースとメソッドの観点から設計されています。これらが追加されるにつれ、デベロッパーが各メソッドを個別に学習する必要が生じるため、負荷が大きく混乱しやすい API サーフェスになる可能性があります。これによって、膨大な時間がかかり、エラーが発生しやすくなることは明白です。
REST のアーキテクチャ スタイルは、主に HTTP/1.1 でうまく動作するように設計されていますが、この問題への対処にも役立ちます。
HTTP REST API はインターネット上で広く普及しているものの、そのトラフィック量は従来の RPC API を下回ります。たとえば、ピーク時におけるアメリカのインターネット トラフィックの約半分は動画コンテンツであり、パフォーマンス上の理由から、このようなコンテンツの配信に REST API が使用されることはほとんどありません。データセンター内部では、多くの企業がソケットベースの RPC API を使用してほとんどのネットワーク トラフィックを処理しています。これは、公開 REST API よりもはるかに大量である可能性があります。
補足記事も有用
Web API: Good Parts
3
アプリケーションの特性を踏まえた上で使いやすい構造を検討する
APIはDBのアクセスIFではない
典型的なユースケースがまずあり、そのために設計するkadoyau.icon
利用者が1つの目的を達成するために複数回アクセスしなければいけないAPIは使いづらいAPI
情報は増やしたほうがいい - (1)
できる限り通信量は減らしたい
情報は減らしたほうがいい - (2)
1, 2は矛盾した要求
よくあるやり方
?fieldsでクエリパラメータとして必要な情報を指定する
Garage にはリソース取得時に必要な値だけ指定して所得する機能があります。 これは例えばレシピのタイトルだけ取得したい時などに材料や手順まで取得してしまうと効率が悪い時に値を絞ったり、逆にレシピに付いている動画情報を取得するなど標準では付加されない情報を取得したりする時に使います。
レスポンス規模によってグルーピングする